Comments should be sent to AppleLink address OPENTPT or Internet address 'opentpt@applelink.apple.com' Unfortunately, we can not provide general technical support via this AppleLink address. Technical support questions should be directed to AppleLink address DEVSUPPORT or Internet address 'devsupport@applelink.apple.com'.
What this release contains
This release includes
• an Installer that will install Open Transport 1.1b14 and Apple Shared Library Manager 2.0 onto your machine.
• a Developer Files folder that contains:
• An ASLM Developer folder contain tools for developing ASLM shared libraries, as well as debugging versions of the Shared Library Manager itself.
• An Open Tpt Client Developer folder that contains documents, header files, MPW libraries, and sample programs
• An Open Tpt Module Developer folder that contains header files and libraries for creating DLPI drivers (See the document "Open Tpt Module Dev. Note" in the documents folder).
• An Open Tpt Protocol Developer folder that contains header files, libraries, and samples for creating configurators (See the document "Open Tpt Module Dev. Note" in the documents folder).
Known Problems
WARNINGS
See also the ReadMe file that accompanies Open Transport
API changes since 1.1b11
• The calls to OTTryClientShutdown and SetupOpenTransport should no longer be used when developing configurators. Instead, configurators should use InitOpenTransport and CloseOpenTransport like normal clients.
Other changes since 1.1b11
• The Open Tpt Protocol Developer portion of the SDK now has a document that starts to document configurators. In addition, there is sample code for a configurator inside the Samples folder.
Bug Fixes since 1.1b11
• Fixed a crash that occured sometimes in "mps_sqe_rip" when unloading modules.
• Fixed a crash that occured sometimes in strrchr when unloading modules.
.Developing Open Transport compliant protocols or drivers
This release does contain information for developers who wish to write DLPI hardware drivers for Open Transport. The document "Open Tpt Driver Dev. Note" describes the procedure for creating a loadable STREAMS module for driver writers. The document does not fully address the needs of protocol implementors, but all of the header files and libraries are present to do the development, and the differences between writing drivers and protocol modules is minimal (You can probably glean the differences by reading the "Open Tpt Driver Dev. Note" document. We still need to document how to get your module usable by the streams environment if "plumbing" is more involved than just "pushing" the module on top of a pre-existing STREAM.
All protocols in the Open Transport architecture are implemented as UNIX System V, release 4.2 STREAMS modules. Open Transport includes a standard STREAMS environment that allows STREAMS modules to be recompiled on the Macintosh. About 20 lines of code, and one ASLM “export” file have to be written to move a standard STREAMS module into the Open Transport environment.
You may want to read about UNIX STREAMS and the TPI and DLPI specifications which define the formats of messages that flow between STREAMS modules.
Sources of information that are applicable to XTI include:
- OSF/1 Operating System: Network Applications Programmer's Guide; Open Software Foundation, Prentice Hall, ISBN 0-13-640145-7
- UNIX Network Programming; W. Richard Stevens, Prentice Hall, ISBN 0-13-949876-1
- Programming UNIX SVR4.2: Network Programming Interhces; UNIX Press (A Prentice Hall title), ISBN 0-13-017641-9
- X/Open CAE Specification: X/Open Transport Interface (XTI); X/Open Company, Ltd. (XO/CAE/91/600) ISBN 1-872630-29-4 (also available on E•T•O in electronic form)
Sources of information that are applicable to STREAMS modules and drivers include:
-STREAMS Modules and Drivers, UNIX SVR4.2; UNIX Press (A Prentice Hall title), ISBN 0-13-066879-6. A much improved revision to the former Programmer’s Guide for STREAMS (listed below). It also includes the TPI specification and a description of DLPI.
- UNIX System V Relase 4: Programmer's Guide: STREAMS; Unix Press (A Prentice Hall title), ISBN - 0-13-020660-1
-UNIX System V Network Programming; Stephen A. Rago, Addison-Wesley Publishing Company, ISBN 0-201-56318-5. A good book for learning to write STREAMS modules and drivers. The book contains (among other things) a discussion of TLI (precursor to XTI) and a complete DPLI STREAMS driver for Ethernet.
- Transport Provider Interface Specification, revision 1.5 (92/12/10); UNIX International, OSI Special Interest Group (also available on E•T•O in electronic form)
- Data Link Provider Interface Specification, revision 2.0.0 (91/08/20); UNIX International, OSI Work Group (also available on E•T•O in electronic form)
Debugger support
The installer will install Open Transport Debugger preferences into the DebuggerPrefs file in your System Folder, if you have one. These debugger prefs contain the ASLM debugger prefs plus Macsbug templates for virtually all structures used in the API. A Macbug dcmd is installed also that can display strings for error messages. For example, typing “OTErr -3158” will tell you what error number -3158 is.
Sample Code
There is a "Samples" folder which contains sample modules and source files.
All of the samples have makefiles that can be used to build them. All of the makefiles use shell variables that must be set to the full pathname of the folders containing the Apple Shared Library Manager and Open Transport header files and object libraries. If you drag the header files and object files from the developer tools diskette to the normal places in MPW, you’d want to set up the shell variables like this before building.
Set ASLMIncludes “{CIncludes}”
Set OTIncludes “{CIncludes}”
Set OTModIncludes “{CIncludes}”
Set OTLibs “{CLibraries}”
Set ASLMLibs “{CLibraries}”
Export ASLMIncludes OTIncludes OTLibs ASLMLibs
After doing this,you can build the sample programs by setting your current MPW directory to be the one containing the samples and using the ‘make’ tool:
Make -f Makefile.SampleModules
OpenTransport header files require the header files that were released on E.T.O. #15 in the "Latest MPW" folder.
Earlier Release Notes
API changes since 1.1b9
• Added OTScheduleInterruptTask API, which is a single call that does the equivalent of calling OTEnterInterrupt, OTScheduleDeferredTask, and OTLeaveInterrupt.
• Added OTScheduleDriverDeferredTask API. This call will eventually give a higher priority to the scheduled task than someone using OTScheduleInterruptTask. Drivers should use this rather than OTScheduleInterruptTask (although right now, it acts exactly the same). Using this function is much faster than doing a "putq" or "qenable" at interrupt time.
• Header files now use #if PRAGMA_ALIGN_SUPPORTED to control whether the #pragma option align=xxxx are used. In addition, the pragma option align=power is used where native PowerPC alignment is used.
Other changes since 1.1b9
• The current heap is set to the system heap before calling a module's InitStreamModule or TerminateStreamModule entry point.
• More updates to the "Open Tpt Module Dev. Note". The major update is how to create a configuration library so that you can override the strings that control panels put into their displays for your devices.
Bug Fixes since 1.1b9
API changes since 1.1b6
• The mi_tpi_conn_req function was not exported - it is now.
• The mps_become_writer function is now documented in the Open Tpt Module Dev. Note.
Other changes since 1.1b6
• The Open Tpt Module Dev. Note has been updated.
• "install_buddies" are now supported. See the Open Tpt Module Dev. Note.
• "qenable" is now a legal function at interrupt time. This provides a compatible way to get yourself scheduled, without invoking OTScheduleDeferredTask.
• The "atmlan" name for ATM Lan Emulation was changed to "atmlane".
• Fixed a problem with the OTGetTimeStamp function on 604 PowerPC machines, where the timestamp was "quantized" to 411 microseconds.
Bug Fixes since 1.1b6
API changes since 1.0.5b3
• mps_become_writer API was added
Other changes since 1.0.5b3
• OTDestroyDeferredTask will no longer return a kEAGAINErr. It always succeeds.
• The OTGetTimeStamp function has been made native on PowerPC. It no longer uses the Microseconds trap.
• An application (StreamLog) is included with the SDK that allows displaying messages that stream modules and drivers send with the "strlog" or "OTStrlog" functions. Source and a Metrowerks project will be included in a future release.
Bug Fixes since 1.0.5b3
• Fixed a problem where TerminateStreamModule may not be called at System Task time.
• Module samples now have the correct prototype for the InitStreamModule function.
API changes since 1.0.5b2
• The enums for the OTStrlog function changed to be a little more meaningful.
• Two new flags were added for the install_flags field of the install_info structure:
kOTModGlobalContext - this flag indicates that even if your driver is handling two different hardware devices, you don't want new static data for the 2nd hardware device. This flag is only meaningful for CFM drivers.
kOTModUsesInterrupts - this flag indicates that your driver uses hardware interrupts and must be locked down in a VM environment. Currently, all PCI drivers that are in the Name Registry are assume to need this flag set, but as you rev your PCI drivers, you should add this bit into your flags.
The kOTModPushAlways bit was obsoleted (it's implied by setting the kOTModIsModule bit).
The kOTModIsLowerMux bit was obsoleted (Open Transport doesn't need to know this).
Added the kOTModIsFilter bit - this flag is used by a module to indicate that it is transparent to the operation of the stream that it is pushed on.
• The kOTPortIsNotShareable bit was obsoleted.
• Many utility APIs were made public and documented in the Open Tpt Module Dev. Note.
Other changes since 1.0.5b2
• Timer resolution was moved back to 1 millisecond from 8 milliseconds. This is where it will stay.
• Opens and Closes of STREAM modules and drivers are not done at System Task time. Use the InitStreamModule and TerminateStreamModule routines to do things that need to be done at System Task Time. In prior releases, Closes were done at System Task time. This caused problems for certain ill-behaved applications, like Quickmail, which do large amounts of networking without ever yielding the CPU.
API changes since 1.0f1
• Added kOTModLowerIsTPI, kOTModUpperIsTPI, kOTModLowerIsDLPI, kOTModLowerIsTPI flags to the flags that should be added to the install_flags field of the install_info structure.
Other changes since 1.0f1
• Timer resolution was changed from 1 milliseconds to 8 milliseconds for performance reasons. What this means is that timers will fire at the closes 8 millisecond boundary to the time requested. Any request for time less than 8 milliseconds will fire in 8 milliseconds.
API changes since 1.0b3
• There was some confusion over the kOTModIsPortDriver bit being dropped and adding a kOTModIsComplexDriver bit. Here's the deal: For standard drivers that can just be "opened" by STREAMS, you should just have the kOTModIsDriver bit set in your install_info. This means that the kOTModIsPortDriver which you used to also set should just be removed.
The kOTModIsComplexDriver bit is a flag to tell Open Transport that when someone wants to open your driver, it is more complicated than just a simple stream open call (an example would be an IPCP driver, which is an IP-related driver that sits on top of PPP and a serial port - It needs to be "pushed" or "linked" with PPP, and then it is clone-opened) . Instead, a "Configurator" is required. The "Configurator" architecture is in the process of being documented, and some documentation should be available by late June.
Other changes since 1.0b3
• Many of the utility functions that are used by STREAM modules used to be in a library called OTUtilityLib that was shared between client and kernel code. Since under Copland, it may not be feasible to share all of this code, OTUtilityLib functions are now exported through the OTKernelLib to allow us to change where the function is implemented without modules having to change. HOWEVER, this means that modules linked with prior version of Open Transport will not work with this version and need to be relinked (If you are linked with 1.0b4 or higher, you can disregard this).
API changes since 1.0b2
NOTE: you should also read the OT Client Release Notes file
• The TPortRecord structure was modified to include an fStreamtab field so that drivers can get to the "real" streamtab being used by Open Transport, if necessary.
• The kOTModIsPortDriver flag for the install_flags in GetOTInstallInfo was dropped. It was never being used by Open Transport. Instead a kOTModIsComplexDriver bit was added to tell Open Transport that the driver is more complicated than just "opening" it.
• The TerminateStreamModule call is now passed the contextPtr (a PCIInfo structure pointer for PCI drivers). This is so that ASLM drivers can recover their context (ASLM drivers don't have per-instantiation globals like CFM drivers do).
Other changes since 1.0b2
• When instantiating a second instance of a CFM module or driver, use the kNewCFragCopy load option so that a new copy of global variables is created for the module/driver.
API changes since 1.0b1
• The TPortRecord structure was modified.
• OTEnterDeferredTask/OTLeaveDeferredTask were renamed to OTEnterCriticalSection/OTLeaveCriticalSection.
Other changes since 1.0b1
• A module returning kENOENTErr from it's ValidateHardware routine will now cause Open Transport to try and find another driver that works.
API changes since 1.0a3
• The OTAllocPortMem and OTFreePortMem functions were added to better support port scanners on non-PCI systems. Using these functions instead of OTAllocMem and OTFreeMem keep the whole STREAMS infrastructure from being loaded when it is not needed.
• The OTLIFO structure was not obsoleted as planned. OTLIFO and OTList still exist separately. There are now no plans to obsolete OTLIFO.
• OTList was changed to a singly-linked list from a doubly-linked list, and the API changed accordingly.
• OTAcquireLock and OTClearLock were added. In this release, they are just front-ends to the atomic set bit instructions. In the next release, OTAcquireLock will be implemented as an actual function. The main reason for this change is that OTAcquireLock can be implemented to have a much short interval where the lock must be retried than is possible with the atomic bit instructions.
• Several new APIs were added to OpenTptModule.h
• OTFindPortByDev now only takes 1 parameter. The 2nd parameter was returning a value that can be determined by inspecting the TPortRecord returned.
• OTEnterInterrupt and OTLeaveInterrupt now take no parameters.
• EnterOTContext and LeaveOTContext were dropped, and are not needed.
• OTDestroyDeferredTask now returns an OSStatus value. OTDestroyDeferredTask may return kEAGAINErr if you are trying to destroy the deferred task while it is scheduled (this can only happen of you destroy the deferred task from within an interrupt service routine or another deferred task, which is rare)
• STREAM drivers are no longer required to call OTInitModule or OTTerminateModule - they still exist for compatibility, but do nothing.
• A new device equate was added for 100 MB Ethernet
• Support for ValidateHardware returning kENOENTErr (the "it's not my hardware" error) has been added.
• Support for Ethernet "Raw Mode" was added via an IOCTL call
• When PCI drivers are loaded, their complete closure is now locked down in memory.
Other changes since 1.0a3
• The Open Tpt Ethernet Dev. Note has been updated to better describe IPX support.
• "Raw mode" support was added for link-layer drivers. See the Open Tpt Ethernet Dev. Note and the Open Tpt 8022 Dev. Note for details.
• The Open Tpt Module Dev. Note is still a placeholder. It contains the prior contents of the Open Tpt Driver Dev. Note.
• For drivers, the only "put" routine is allowed at primary interrupt time is a "putq" to your own lower queue. This allowed us to take out special code that slows things down in all the other "put" routines. You can always schedule your own deferred task to make one of the other "put" function calls.
• OTAllocMsg now uses the "esballoc" function instead of the "esballoca" function. What this means is that clients are now allowed to overwrite data in your buffers until the buffer is freed. If this is not desireable, use esballoca directly.
